Migrate the API naming guidelines into the DocC catalog#74
Migrate the API naming guidelines into the DocC catalog#74heckj wants to merge 3 commits intoswiftlang:mainfrom
Conversation
| ### Naming — Strive for Fluent Usage | ||
|
|
||
| - <doc:API-0006> | ||
| - <doc:API-0007> |
There was a problem hiding this comment.
This is a striking example of a guideline that doesn't stand on its own as a document due to brevity. There are others that are duals of each other (such as "Include words to avoid ambiguity" and "Omit needless words") which take on a different color if separated.
Have you considered instead separating the guidelines such that each document encompasses one of the headings here (e.g., grouping guidelines 6 through 13) or something of that ilk?
Edit: I'm not sure why the heading says the review is on behalf of the group—this is just me wearing my individual hat and not a comment from the steering group.
There was a problem hiding this comment.
The GH thing is labelling it as the group since you're a part of that group. No worries, I get you're not explicitly speaking for the whole group.
Yeah, 7 is incredibly short - and if I were doing this from scratch, I'd likely make some explicit choices about pairing things up, but wanted to start with each section from the original as it's own guideline to start the conversation. While it's incredibly short, the content is still focused, even if it's effectively just the abstract of the article with no deeper content inside it.
There was a problem hiding this comment.
For this guideline in particular (factory methods), I think having it separated is actually the perfect opportunity to improve it (not in this PR of course, but as part of a future effort).
Without ratholing too much on this specific rule, in my experience I think it's been largely misunderstood. I've reviewed a great amount of Swift code where people interpret "factory method" is just "any method that creates and returns some new value" and sprinkle make all over the place, when (based on my own observations of standard library patterns) I think it's supposed to be interpreted more narrowly like the "factory design pattern" where a method is implemented by multiple concrete types and each can return a different concrete type satisfying a common requirement.
That's the kind of elaboration that we can and should do on each of these rules once the initial changes land, because in the original one-pager form, it would have been far too unwieldy to present that much information. There may be some rules where there really is just nothing to be said, but for the most part I think this split presentation will let us really flesh these out in more detail, improving on an already valuable document.
Summary
This is a fairly direct migration of the API naming guidelines. The first commit is explicitly the content from the swift-org-website Jekyll based markdown, then the following commits break up that code and translate the content over to DocC format. I chose, in particular, to break this up so that each guideline became it's own "article" with a number, using a prefix of "API" for the numbering scheme, so that each one - when published - is extremely easy to reference directly with a constant URI.
This PR hasn't changed any of the content - although I'd recommend making a few basic changes that align better with our general style guidelines that have evolved since this was originally written. In particular, I'd likely remove the bold in the abstracts and remove any latin abbreviations- but I wanted to set it up for review and looking prior to any additional editorial changes for better readability.
Related Issue
Closes: #44
Testing
cd api-guidelines swift package --disable-sandbox preview-documentation open http://localhost:8080/documentation/apiguidelinesBuild Verification
swift package generate-documentation --analyze --warnings-as-errorssuccessfullyswift package --disable-sandbox preview-documentationContent Review
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.